Inside Macintosh: Imaging with QuickDraw
Previous | Chapter Top | Chapter Contents | Next |
As described in "Collecting Picture Information," , your application can use the GetPictInfo , GetPixMapInfo , and NewPictInfo functions to gather information about pictures, pixel maps, and bitmaps. Each of these functions can gather up to 256 colors in ColorTable and Palette records. In the colorPickMethod parameter to these functions, you specify how they should select which colors to gather. These Picture Utilities functions provide two color-picking methods: the first selects the most frequently used colors, and the second selects a weighted distribution of the existing colors.
You can also create your own color-picking method. You must compile it as a resource of type 'cpmt' and write its entry point in assembly language. To use this color-picking method ( 'cpmt' ) resource, pass its resource ID (which must be greater than 127) in the colorPickMethod parameter to these Picture Utilities functions. These functions call your color-picking method's entry point and pass one of four possible selectors in register D0. These functions pass their parameters on the stack. As shown in Table 7-1 , each selector requires your color-picking method to call a different routine, which should return its results in register D0.
MyInitPickMethod
|
|
MyRecordColors
|
|
MyCalcColorTable
|
|
MyDisposeColorPickMethod
|
Your color-picking method ( 'cpmt' ) resource should include a routine that specifies its color bank (that is, the structure into which all the colors of a picture, pixel map, or bitmap are gathered) and allocates whatever data your color-picking method needs. This routine is explained next as a Pascal function declared as MyInitPickMethod .
Your MyInitPickMethod function can let the Picture Utilities generate a color bank consisting of a histogram (that is, frequency counts of each color) to a resolution of 5 bits per color. Or, your MyInitPickMethod function can specify that your application has its own custom color bank--for example, a histogram to a resolution of 8 bits per color.
If you create your own custom color bank, your 'cpmt' resource should include a routine that gathers and stores colors; this routine is described on MyRecordColors as a Pascal function declared as MyRecordColors .
For the number of colors your application requests using the Picture Utilities, your 'cpmt' resource should include a routine that determines which colors to select from the color bank and then fills an array of ColorSpec records with those colors; this routine is described on MyCalcColorTable as a Pascal function declared as MyCalcColorTable . The Picture Utilities function that your application initially called then returns these colors in a Palette record or ColorTable record, as specified by your application when it first called the Picture Utilities function.
Your 'cpmt' resource should include a routine that releases the memory allocated by your MyInitPickMethod routine. The routine that releases memory is described on MyDisposeColorPickMethod as a Pascal function declared as MyDisposeColorPickMethod .
If your routines return an error, that error is passed back to the GetPictInfo , GetPixMapInfo , or NewPictInfo function, which in turn passes the error to your application as a function result.
Your color-picking method ( 'cpmt' ) resource should include a routine that specifies its color bank and allocates whatever data your color-picking method needs. Here is how you would declare this routine if it were a Pascal function named MyInitPickMethod :
FUNCTION MyInitPickMethod (colorsRequested: Integer;
VAR dataRef: LongInt;
VAR colorBankType: Integer): OSErr;
CONST
colorBankIsCustom = -1; {gathers colors into a }
{ custom color bank}
colorBankIsExactAnd555 = 0; {gathers exact colors }
{ if there are less }
{ than 256 unique }
{ colors in picture; }
{ otherwise gathers }
{ colors for picture }
{ in a 5-5-5 histogram}
colorBankIs555 = 1; {gathers colors into a }
{ 5-5-5 histogram}
Your MyInitPickMethod routine should allocate whatever data your color-picking method needs and store a handle to your data in the location pointed to by the dataRef parameter. In the colorBankType parameter, your MyInitPickMethod routine must also return the type of color bank your color-picking method uses for color storage. If your MyInitPickMethod routine generates any error, it should return the error as its function result.
The 5-5-5 histogram that the Picture Utilities provide if you return the ColorBankIs555 or ColorBankIsExactAnd555 constant in the colorBankType parameter is like a reversed cSpecArray record, which is an array of ColorSpec records. (The cSpecArray and ColorSpec records are described in the chapter "Color QuickDraw" in this book.) This 5-5-5 histogram is an array of 32,768 integers, where the index into the array is the color: 5 bits of red, followed by 5 bits of green, followed by 5 bits of blue. Each entry in the array is the number of colors in the picture that are approximated by the index color for that entry.
For example, suppose there were three instances of the following color in the pixel map:
This color would be represented by index % 0 11011-01111-01011 (in hexadecimal, $6DEB), and the value in the histogram at this index would be 3, because there are three instances of this color.
When you return the colorBankIsCustom constant in the colorBankType parameter to your MyInitPickMethod function (described in the preceding section), your color-picking method ( 'cpmt' ) resource must include a routine that creates this color bank; for example, your application may want to create a histogram with a resolution of 8 bits per color. Here is how you would declare this routine if it were a Pascal function named MyRecordColors :
FUNCTION MyRecordColors (dataRef: LongInt;
colorsArray: RGBColorArray;
colorCount: LongInt;
VAR uniqueColors: LongInt): OSErr;
TYPE RGBColorArray = ARRAY[0..0] OF RGBColor;
Your MyRecordColors routine should store each color encountered in a picture or pixel into its own color bank. The Picture Utilities call MyRecordColors only if your MyInitPickMethod routine returns the constant colorBankIsCustom in the colorBankType parameter. The Picture Utilities functions call MyRecordColors for all the colors in the picture, pixel map, or bitmap. If your MyRecordColors routine generates any error, it should return the error as its function result.
Your color-picking method ( 'cpmt' ) resource should include a routine that selects as many colors as are requested by your application from the color bank for a picture or pixel map and then fills these colors into an array of ColorSpec records.
Here is how you would declare this routine if it were a Pascal function named MyCalcColorTable :
FUNCTION MyCalcColorTable (dataRef: LongInt;
colorsRequested: Integer;
colorBankPtr: Ptr;
VAR resultPtr: CSpecArray): OSErr;
Selecting from the color bank created for the picture, bitmap, or pixel map being examined, your MyCalcColorTable routine should fill an array of ColorSpec records with the number of colors requested in the colorsRequested parameter and return this array in the resultPtr parameter. If your MyCalcColorTable routine generates any error, it should return the error as its function result.
If more colors are requested than the picture contains, fill the remaining entries with black (0000 0000 0000).
The colorBankPtr parameter is of type Ptr because the data stored in the color bank is of the type specified by your MyInitPickMethod routine (described on MyInitPickMethod ). Thus, if you specified colorBankIs555 in the colorBankType parameter, the color bank would be an array of integers. However, if the Picture Utilities support other data types in the future, the colorBankPtr parameter could point to completely different data types.
Your 'cpmt' resource should include a routine that releases the memory allocated by your MyInitPickMethod routine (which is described on MyInitPickMethod ). Here is how you would declare this routine if it were a Pascal function named MyDisposeColorPickMethod :
FUNCTION MyDisposeColorPickMethod (dataRef: LongInt): OSErr;